An AAAAFFFFffffiiiilllleeeehhhhaaaannnnddddlllleeee is an opaque structure which is used to read audio data
and auxiliary information from an existing file, or write audio data and
auxiliary information to a new file. The AAAAFFFFffffiiiilllleeeehhhhaaaannnnddddlllleeee structure
maintains state information such as the current location of the logical
audio sample read/write pointer and the logical locations of the data
read/write pointers for the various miscellaneous data chunks.
Following is a list of the functions included in the Audio File Library.
Functions for performing basic operations on an AAAAFFFFffffiiiilllleeeehhhhaaaannnnddddlllleeee structure,
and for allocating and freeing AAAAFFFFffffiiiilllleeeesssseeeettttuuuupppp and AAAAFFFFffffiiiilllleeeehhhhaaaannnnddddlllleeee structures:
aaaaffffCCCClllloooosssseeeeFFFFiiiilllleeee(3dm) close and deallocate an AFfilehandle
aaaaffffFFFFrrrreeeeeeeeFFFFiiiilllleeeeSSSSeeeettttuuuupppp(3dm) deallocate an AFfilesetup struct
aaaaffffIIIIddddeeeennnnttttiiiiffffyyyyFFFFDDDD(3dm) determine the audio file format for a Unix
file descriptor
aaaaffffIIIIddddeeeennnnttttiiiiffffyyyyNNNNaaaammmmeeeeddddFFFFDDDD(3dm) determine the audio file format for a Unix
file descriptor and supplied filename
aaaaffffNNNNeeeewwwwFFFFiiiilllleeeeSSSSeeeettttuuuupppp(3dm) create an AFfilesetup struct
aaaaffffOOOOppppeeeennnnFFFFDDDD(3dm) create an AFfilehandle for a Unix file
descriptor
aaaaffffOOOOppppeeeennnnFFFFiiiilllleeee(3dm) create an AFfilehandle for a named file
aaaaffffRRRReeeeaaaaddddMMMMiiiisssscccc(3dm) read buffer of miscellaneous data
aaaaffffRRRReeeeaaaaddddFFFFrrrraaaammmmeeeessss(3dm) read a buffer of sample frames from an
audio track
aaaaffffSSSSeeeeeeeekkkkMMMMiiiisssscccc(3dm) seek to given location in miscellaneous
data
aaaaffffSSSSeeeettttCCCCoooonnnnvvvveeeerrrrssssiiiioooonnnnPPPPaaaarrrraaaammmmssss(3dm) set, via ddddmmmmPPPPaaaarrrraaaammmmssss(3dm), the parameters
used for format and rate conversion in an
audio track. This includes the rate
conversion algorithm, if any, and the
dithering algorithm.
aaaaffffSSSSeeeettttEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr(3dm) supply an error reporting routine for the
library
aaaaffffSSSSeeeettttTTTTrrrraaaacccckkkkPPPPCCCCMMMMMMMMaaaappppppppiiiinnnngggg(3dm) set the PCM mapping (slope, intercept, min
aaaaffffSSSSeeeettttVVVViiiirrrrttttuuuuaaaallllFFFFoooorrrrmmmmaaaattttPPPPaaaarrrraaaammmmssss(3dm) set (via ddddmmmmPPPPaaaarrrraaaammmmssss(3dm)) the virtual
sample format, channels, byte order, etc.
for a track
aaaaffffGGGGeeeettttVVVViiiirrrrttttuuuuaaaallllFFFFrrrraaaammmmeeeeSSSSiiiizzzzeeee(3dm) get the frame size in bytes for the audio
data buffer
aaaaffffGGGGeeeettttVVVViiiirrrrttttuuuuaaaallllPPPPCCCCMMMMMMMMaaaappppppppiiiinnnngggg(3dm) get the PCM mapping (slope, intercept,
min clip, max clip) for the audio data
buffer
aaaaffffSSSSeeeettttVVVViiiirrrrttttuuuuaaaallllPPPPCCCCMMMMMMMMaaaappppppppiiiinnnngggg(3dm) set the PCM mapping (slope, intercept,
min clip, max clip) for the audio data
buffer
aaaaffffGGGGeeeettttVVVViiiirrrrttttuuuuaaaallllRRRRaaaatttteeee(3dm) get the sampling rate of the audio data
buffer.
aaaaffffSSSSeeeettttVVVViiiirrrrttttuuuuaaaallllRRRRaaaatttteeee(3dm) set the sampling rate for the audio data
buffer. Data will be automatically
rate-converted to match the virtual rate
setting.
aaaaffffGGGGeeeettttVVVViiiirrrrttttuuuuaaaallllSSSSaaaammmmpppplllleeeeFFFFoooorrrrmmmmaaaatttt(3dm) get the sample format and resolution
(sample width) of the audio data buffer
aaaaffffSSSSeeeettttVVVViiiirrrrttttuuuuaaaallllSSSSaaaammmmpppplllleeeeFFFFoooorrrrmmmmaaaatttt(3dm) set the sample format and resolution of
the audio data buffer
Functions for setting initialization parameters in an AAAAFFFFffffiiiilllleeeesssseeeettttuuuupppp
structure (which is used to configure an audio file when the file is
opened):
aaaaffffIIIInnnniiiittttAAAAEEEESSSSCCCChhhhaaaannnnnnnneeeellllDDDDaaaattttaaaa(3dm) reserve space for AES channel status in a
new file
aaaaffffIIIInnnniiiittttBBBByyyytttteeeeOOOOrrrrddddeeeerrrr(3dm) configure the byte order for the audio
data in a track
aaaaffffIIIInnnniiiittttCCCChhhhaaaannnnnnnneeeellllssss(3dm) configure number of channels for a new
track
aaaaffffIIIInnnniiiittttCCCCoooommmmpppprrrreeeessssssssiiiioooonnnn(3dm) configure compression type for a track
aaaaffffIIIInnnniiiittttCCCCoooommmmpppprrrreeeessssssssiiiioooonnnnPPPPaaaarrrraaaammmmssss(3dm) configure compression type and algorithm-
specific parameters
aaaaffffIIIInnnniiiittttFFFFiiiilllleeeeFFFFoooorrrrmmmmaaaatttt(3dm) configure the format for a new file
aaaaffffIIIInnnniiiittttFFFFoooorrrrmmmmaaaattttPPPPaaaarrrraaaammmmssss(3dm) configure (via ddddmmmmPPPPaaaarrrraaaammmmssss(3dm)) the sample
The file descriptor returned by aaaaffffGGGGeeeettttFFFFDDDD(3dm) is not intended to allow
users to read, write, and seek in the file without the knowledge of the
Audio File Library. Doing so will cause the library to give
unpredictable results unless the user saves and restores the file
position whenever they modify it. This can be done using
aaaaffffSSSSaaaavvvveeeeFFFFiiiilllleeeePPPPoooossssiiiittttiiiioooonnnn(3dm) and aaaaffffRRRReeeessssttttoooorrrreeeeFFFFiiiilllleeeePPPPoooossssiiiittttiiiioooonnnn(3dm). The same
precautions must be also used with the file descriptor given to
afOpenFD(). Developers can get the offset of the audio data in an audio
file via the aaaaffffGGGGeeeettttDDDDaaaattttaaaaOOOOffffffffsssseeeetttt(3dm) function.
Users cannot make multiple, simultaneous, uncoordinated AF calls from
different threads to set or access the library's global state--namely,
the error handler function. If two threads simultaneously try to set the
global error handler (even the same error handler), the behavior is
undefined. See below for an alternative.
Furthermore, if the user writes an error handler, then makes multiple,
simultaneous, uncoordinated AF calls on different filehandles from
different threads, and both AF calls issue an error simultaneously, then
two instances of the user's error handler will be called in a
simultaneous, uncoordinated manner in two threads. If this situation is
possible in a user's program, the user should use semaphores in their
error handler in order to make sure their handler doesn't try and report
or deal with two errors at the same time. Note that any AF function can
cause an AF error to occur. Do not assume a function will not produce
and error just because it is simple.
A new form of MT-safe error handling mechanism is now available; if an
application wishes to use it, it should call aaaaffffSSSSeeeettttEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr(3dm) with
a NULL value to disable the old error handler system, and call
ddddmmmmGGGGeeeettttEEEErrrrrrrroooorrrr(3dm) when a function returns an error value. The application
must also add ----llllddddmmmmeeeeddddiiiiaaaa to the link arguments if it calls this routine.
Now the most important caveat: Users cannot make multiple, simultaneous,
uncoordinated AF calls on the same AFfilehandle from different threads,
even if the order of execution of those calls does not matter to the
user. Doing so will very likely cause a core dump, or at least
corruption of the AFfilehandle. This behavior will never be changed, as
we refuse to make our developers pay the price of semaphore locking code
at the beginning and end of every afReadFrames and afWriteFrames call.
Most users do not need, and in fact really do not want, semaphore
protection that is built-in to the AF calls themselves.
FFFFIIIILLLLEEEESSSS
Audio File Library header file:
/usr/include/dmedia/audiofile.h
Audio File Library code examples:
/usr/share/src/dmedia/soundcommands/*
/usr/share/src/dmedia/soundfile/*
The programs ppppllllaaaayyyyaaaaiiiiffffffff((((1111)))) and ppppllllaaaayyyyaaaaiiiiffffcccc((((1111)))) are now installed as links to
the program ssssffffppppllllaaaayyyy((((1111)))); rrrreeeeccccoooorrrrddddaaaaiiiiffffffff((((1111)))) and rrrreeeeccccoooorrrrddddaaaaiiiiffffcccc((((1111)))) are now installed
as links to the program ssssffffrrrreeeeccccoooorrrrdddd((((1111)))). These programs are based on calls
to the and Audio File Library and Audio Library.
The file aaaaiiiiffffccccccccoooonnnnvvvveeeerrrrtttt....cccc is actually the source for several programs which
are installed in /usr/sbin: aaaaiiiiffffcccc2222aaaaiiiiffffffff((((1111)))), aaaaiiiiffffffff2222aaaaiiiiffffcccc((((1111)))), aaaaiiiiffffccccccccoooommmmpppprrrreeeessssssss((((1111)))),
and aaaaiiiiffffccccddddeeeeccccoooommmmpppprrrreeeessssssss((((1111)))).
